---
title: .moon/toolchain.{pkl,yml}
toc_max_heading_level: 6
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import HeadingApiLink from '@site/src/components/Docs/HeadingApiLink';
import RequiredLabel from '@site/src/components/Docs/RequiredLabel';
import VersionLabel from '@site/src/components/Docs/VersionLabel';

The `.moon/toolchain.yml` file configures the toolchain and the workspace development environment.
This file is _optional_.

Managing tool version's within the toolchain ensures a deterministic environment across any machine
(whether a developer, CI, or production machine).

```yaml title=".moon/toolchain.yml"
$schema: 'https://moonrepo.dev/schemas/toolchain.json'
```

:::info

Toolchain configuration can also be written in [Pkl](../guides/pkl-config) instead of YAML.

:::

## `extends`

<HeadingApiLink to="/api/types/interface/ToolchainConfig#extends" />

Defines one or many external `.moon/toolchain.yml`'s to extend and inherit settings from. Perfect
for reusability and sharing configuration across repositories and projects. When defined, this
setting must be an HTTPS URL _or_ relative file system path that points to a valid YAML document!

```yaml title=".moon/toolchain.yml" {1}
extends: 'https://raw.githubusercontent.com/organization/repository/master/.moon/toolchain.yml'
```

:::caution

Settings will be merged recursively for blocks, with values defined in the local configuration
taking precedence over those defined in the extended configuration.

:::

## `moon`<VersionLabel version="1.29.0" />

<HeadingApiLink to="/api/types/interface/ToolchainConfig#moon" />

Configures how moon will receive information about latest releases and download locations.

### `manifestUrl`

<HeadingApiLink to="/api/types/interface/MoonConfig#manifestUrl" />

Defines an HTTPS URL in which to fetch the current version information from.

```yaml title=".moon/toolchain.yml" {2}
moon:
  manifestUrl: 'https://proxy.corp.net/moon/version'
```

### `downloadUrl`

<HeadingApiLink to="/api/types/interface/MoonConfig#downloadUrl" />

Defines an HTTPS URL in which the moon binary can be downloaded from. The download file name is
hard-coded and will be appended to the provided URL.

Defaults to downloading from GitHub: https://github.com/moonrepo/moon/releases

```yaml title=".moon/toolchain.yml" {2}
moon:
  downloadUrl: 'https://github.com/moonrepo/moon/releases/latest/download'
```

## `proto`<VersionLabel version="1.39.0" />

<HeadingApiLink to="/api/types/interface/ToolchainConfig#proto" />

Configures how moon integrates with and utilizes [proto](/proto).

### `version`

<HeadingApiLink to="/api/types/interface/ProtoConfig#version" />

The version of proto to install and run toolchains with. If proto or this version of proto has not
been installed yet, it will be installed automatically when running a task.

```yaml title=".moon/toolchain.yml" {2}
proto:
  version: '0.51.0'
```

## Go

## `unstable_go`<VersionLabel version="1.38.0" />

<HeadingApiLink to="/api/types/interface/ToolchainConfig#go" />

Enables and configures Go. This setting enables the new WASM powered Go toolchain.

### `version`

<HeadingApiLink to="/api/types/interface/GoConfig#version" />

Defines the explicit Go toolchain
[version specification](../concepts/toolchain#version-specification) to use. If this field is _not
defined_, the global `go` binary will be used.

```yaml title=".moon/toolchain.yml" {2}
unstable_go:
  version: '1.24.0'
```

> Version can also be defined with [`.prototools`](../proto/config).

### `bins`

<HeadingApiLink to="/api/types/interface/GoConfig#bins" />

A list of binaries to install globally into Go (`~/go/bin`) using `go install`. This setting
requires a list of URLs or binary configuration objects with the following fields:

- `bin` (required) - URL of the binary.
- `local` - Only install the binary locally, and not in CI.

```yaml title=".moon/toolchain.yml" {2-5}
unstable_go:
  bins:
    - 'golang.org/x/tools/gopls'
    - bin: 'github.com/revel/cmd/revel@1'
      local: true
```

### `tidyOnChange`

<HeadingApiLink to="/api/types/interface/GoConfig#tidyOnChange" />

Tidy modules when dependencies or `go.sum` changes by running `go mod tidy`. This setting is ignored
when using Go workspaces. Defaults to `false`.

```yaml title=".moon/toolchain.yml" {2}
unstable_go:
  tidyOnChange: true
```

### `vendorDir`

<HeadingApiLink to="/api/types/interface/GoConfig#vendorDir" />

A relative path to the vendor directory from the dependencies root, as generated with
`go mod vendor`. If vendored with the default name of "vendor", this setting can be omitted.

```yaml title=".moon/toolchain.yml" {2}
unstable_go:
  vendorDir: 'custom/vendor/path'
```

### `workspaces`

<HeadingApiLink to="/api/types/interface/GoConfig#workspaces" />

Enables support for [Go workspaces](https://go.dev/ref/mod#workspaces) and will attempt to locate
the dependencies root by locating the `go.work` file, and parsing `go.work.sum` files. This
functionality will take precedence over `go.sum` files. Defaults to `true`.

```yaml title=".moon/toolchain.yml" {2}
unstable_go:
  workspaces: true
```

## JavaScript

## `unstable_javascript`<VersionLabel version="1.40.0" />

<HeadingApiLink to="/api/types/interface/ToolchainConfig#unstable_javascript" />

Enables and configures JavaScript using the new WASM plugin. This core JavaScript toolchain depends
on these other JavaScript ecosystem toolchains:

- Runtimes: [`unstable_bun`](#unstable_bun), [`unstable_deno`](#unstable_deno),
  [`unstable_node`](#unstable_node)
- Package managers: [`unstable_bun`](#unstable_bun), [`unstable_deno`](#unstable_deno),
  [`unstable_npm`](#unstable_npm), [`unstable_pnpm`](#unstable_pnpm),
  [`unstable_yarn`](#unstable_yarn)

### `dedupeOnLockfileChange`

<HeadingApiLink to="/api/types/interface/JavaScriptConfig#dedupeOnLockfileChange" />

Will dedupe dependencies after they have been installed, added, removed, or changed in any way, in
an effort to keep the workspace tree as clean and lean as possible. Defaults to `true`.

```yaml title=".moon/toolchain.yml" {2}
unstable_javascript:
  dedupeOnLockfileChange: true
```

### `dependencyVersionFormat`

<HeadingApiLink to="/api/types/interface/JavaScriptConfig#dependencyVersionFormat" />

When [syncing project dependencies](#syncprojectworkspacedependencies), customize the format that
will be used for the dependency version range. The following formats are supported (but use the one
most applicable to your chosen package manager):

- `file` (npm default) - Uses `file:../relative/path` and copies package contents.
- `link` - Uses `link:../relative/path` and symlinks package contents.
- `star` - Uses an explicit `*`.
- `version` - Uses the explicit version from the dependent project's `package.json`, e.g., "1.2.3".
- `version-caret` - Uses the version from the dependent project's `package.json` as a caret range,
  e.g., "^1.2.3".
- `version-tilde` - Uses the version from the dependent project's `package.json` as a tilde range,
  e.g., "~1.2.3".
- `workspace` (bun/pnpm/yarn default) - Uses `workspace:*`, which resolves to "1.2.3". Requires
  package workspaces.
- `workspace-caret` - Uses `workspace:^`, which resolves to "^1.2.3". Requires package workspaces.
- `workspace-tilde` - Uses `workspace:~`, which resolves to "~1.2.3". Requires package workspaces.

```yaml title=".moon/toolchain.yml" {2}
unstable_javascript:
  dependencyVersionFormat: 'link'
```

> This setting does not apply to peer dependencies, as they will always use a format of
> `^<major>.0.0`. Furthermore, if a package manager does not support a chosen format, it will
> fallback to another format!

### `inferTasksFromScripts`

<HeadingApiLink to="/api/types/interface/JavaScriptConfig#inferTasksFromScripts" />

Will infer and automatically create [tasks](../concepts/task) from `package.json` scripts. Defaults
to `false`.

This requires the [project's language](./project#language) to be "javascript" or "typescript", a
`package.json` to exist in the project, and will take the following into account:

- Script names will be converted to kebab-case, and will become the task ID.
- Script names that contain `dev`, `start`, `serve`, or `preview` will be considered local only.
- Pre, post, and life cycle hooks are ignored.
- Tasks defined in `.moon/tasks.yml` or `moon.yml` take precedence over scripts of the same name.

To verify inferred tasks, run [`moon project <id>`](../commands/project) (pass `--json` to view raw
config and options). Tasks that are inferred will run through the configured package manager.

```yaml title=".moon/toolchain.yml" {2}
unstable_javascript:
  inferTasksFromScripts: true
```

### `packageManager`

<HeadingApiLink to="/api/types/interface/JavaScriptConfig#packageManager" />

Defines which package manager to utilize when installing dependencies. Supports `npm`, `pnpm`,
`yarn`, `deno`, or `bun`. Defaults to no package manager.

```yaml title=".moon/toolchain.yml" {2}
unstable_javascript:
  packageManager: 'yarn'
```

:::info

When this setting is configured, it will require the target toolchain
([`unstable_bun`](#unstable_bun), [`unstable_deno`](#unstable_deno),
[`unstable_node`](#unstable_node), [`unstable_npm`](#unstable_npm),
[`unstable_pnpm`](#unstable_pnpm), or [`unstable_yarn`](#unstable_yarn)) to also be configured.

:::

### `rootPackageDependenciesOnly`

<HeadingApiLink to="/api/types/interface/JavaScriptConfig#rootPackageDependenciesOnly" />

Supports the "single version policy" or "one version rule" patterns by only allowing dependencies in
the root `package.json`, and only installing dependencies in the workspace root, and not within
individual projects. Defaults to `false`.

```yaml title=".moon/toolchain.yml" {2}
unstable_javascript:
  rootPackageDependenciesOnly: true
```

### `syncPackageManagerField`

<HeadingApiLink to="/api/types/interface/JavaScriptConfig#syncPackageManagerField" />

Will sync the currently configured [package manager](#packagemanager) and its version to the
`packageManager` field in the root `package.json`. This setting does nothing if the package manager
or version is not defined. Defaults to `true`.

```yaml title=".moon/toolchain.yml" {2}
unstable_javascript:
  syncPackageManagerField: true
  packageManager: 'pnpm'

unstable_pnpm:
  version: '9.0.0'
```

A quick example on how this works. Given the above, the following field will be injected:

```json title="package.json"
{
  // ...
  "packageManager": "pnpm@9.0.0"
}
```

### `syncProjectWorkspaceDependencies`

<HeadingApiLink to="/api/types/interface/JavaScriptConfig#syncProjectWorkspaceDependencies" />

Will sync a project's [dependencies](../concepts/project#dependencies) as manifest dependencies
within the project's `package.json`. If a dependent project does not have a `package.json`, or if a
dependency of the same name has an explicit version already defined, the sync will be skipped.
Defaults to `true`.

```yaml title=".moon/toolchain.yml" {2}
unstable_javascript:
  syncProjectWorkspaceDependencies: true
```

## `bun`<VersionLabel version="1.17.0" />

<HeadingApiLink to="/api/types/interface/ToolchainConfig#bun" />

Enables and configures [Bun](../guides/javascript/bun-handbook) using the legacy implementation.

:::warning

This toolchain has been deprecated. We suggest using [`unstable_bun`](#unstable_bun) instead!

:::

### `version`

<HeadingApiLink to="/api/types/interface/BunConfig#version" />

Defines the explicit Bun toolchain
[version specification](../concepts/toolchain#version-specification) to use. If this field is _not
defined_, the global `bun` binary will be used.

```yaml title=".moon/toolchain.yml" {2}
bun:
  version: '1.0.0'
```

> Version can also be defined with [`.prototools`](../proto/config).

### `installArgs`<VersionLabel version="1.22.0" />

<HeadingApiLink to="/api/types/interface/BunConfig#installArgs" />

Customize the arguments that will be passed to the `bun install` command, when the `InstallDeps`
action is triggered in the pipeline. These arguments are used both locally and in CI.

```yaml title=".moon/toolchain.yml" {2}
bun:
  installArgs: ['--frozen-lockfile']
```

### Inherited from `node`

Since Bun and Node.js have a lot of overlap in functionality, the following [`node`](#node) settings
can also be configured within `bun`:

- [`dependencyVersionFormat`](#dependencyversionformat)
- [`inferTasksFromScripts`](#infertasksfromscripts)
- [`rootPackageOnly`](#rootpackageonly)
- [`syncProjectWorkspaceDependencies`](#syncprojectworkspacedependencies)

```yaml title=".moon/toolchain.yml" {2-4}
bun:
  dependencyVersionFormat: 'workspace'
  inferTasksFromScripts: true
  rootPackageOnly: true
  syncProjectWorkspaceDependencies: true
```

## `unstable_bun`<VersionLabel version="1.40.0" />

<HeadingApiLink to="/api/types/interface/ToolchainConfig#unstable_bun" />

Enables and configures [Bun](../guides/javascript/bun-handbook) using the new WASM plugin.

:::info

This toolchain requires the [`unstable_javascript`](#unstable_javascript) toolchain to also be
enabled.

:::

### `version`

<HeadingApiLink to="/api/types/interface/BunConfig#version" />

Defines the explicit Bun toolchain
[version specification](../concepts/toolchain#version-specification) to use. If this field is _not
defined_, the global `bun` binary will be used.

```yaml title=".moon/toolchain.yml" {2}
unstable_bun:
  version: '1.0.0'
```

> Version can also be defined with [`.prototools`](../proto/config).

### `executeArgs`

<HeadingApiLink to="/api/types/interface/BunConfig#executeArgs" />

Customize the arguments that will be appended to all `bun`-based task commands. Arguments will be
appended after the `bun` executable, but before task specific arguments.

```yaml title=".moon/toolchain.yml" {2}
unstable_bun:
  executeArgs: ['--bun', '--silent']
```

### `installArgs`

<HeadingApiLink to="/api/types/interface/BunConfig#installArgs" />

Customize the arguments that will be passed to the `bun install` command, when the
`InstallDependencies` action is triggered in the pipeline. These arguments are used both locally and
in CI.

```yaml title=".moon/toolchain.yml" {2}
unstable_bun:
  installArgs: ['--frozen-lockfile']
```

## `deno`

<HeadingApiLink to="/api/types/interface/ToolchainConfig#deno" />

Enables and configures [Deno](../guides/javascript/deno-handbook).

:::warning

This toolchain has been deprecated. We suggest using [`unstable_deno`](#unstable_deno) instead!

:::

### `version`<VersionLabel version="1.21.0" />

<HeadingApiLink to="/api/types/interface/DenoConfig#version" />

Defines the explicit Deno toolchain
[version specification](../concepts/toolchain#version-specification) to use. If this field is _not
defined_, the global `deno` binary will be used.

```yaml title=".moon/toolchain.yml" {2}
deno:
  version: '1.40.0'
```

### `bins`<VersionLabel version="1.10.0" />

<HeadingApiLink to="/api/types/interface/DenoConfig#bins" />

A list of binaries to install globally into Deno (`~/.deno/bin`). This setting requires a list of
URLs or binary configuration objects with the following fields:

- `bin` (required) - URL of the binary.
- `name` - Provide a custom name for the binary.
- `local` - Only install the binary locally, and not in CI.
- `force` - Force install the binary. This _should_ be toggled for one-offs.

```yaml title=".moon/toolchain.yml" {2-5}
deno:
  bins:
    - 'https://deno.land/std@0.192.0/http/file_server.ts'
    - bin: 'https://deno.land/std@0.192.0/http/file_server.ts'
      name: 'fs'
```

### `depsFile`

<HeadingApiLink to="/api/types/interface/DenoConfig#depsFile" />

Path to the
[dependencies file](https://deno.land/manual/basics/modules#it-seems-unwieldy-to-import-urls-everywhere)
that's used for re-exporting external libraries. This file is heavily used in hashing and caching
related scenarios. Defaults to `deps.ts`.

```yaml title=".moon/toolchain.yml" {2}
deno:
  depsFile: 'src/deps.ts'
```

### `installArgs`<VersionLabel version="1.32.0" />

<HeadingApiLink to="/api/types/interface/DenoConfig#installArgs" />

Customize the arguments that will be passed to the `deno install` command (Deno >= v2), when the
`InstallDeps` action is triggered in the pipeline. These arguments are used both locally and in CI.

```yaml title=".moon/toolchain.yml" {2}
deno:
  installArgs: ['--frozen']
```

### `lockfile`

<HeadingApiLink to="/api/types/interface/DenoConfig#lockfile" />

Enables lockfile (`deno.lock`) support for Deno dependencies. When enabled, will run `deno cache`
(v1) or `deno install` (v2+) as part of the dependency installation action. Defaults to `false`.

```yaml title=".moon/toolchain.yml" {2}
deno:
  lockfile: true
```

## `unstable_deno`<VersionLabel version="1.41.0" />

<HeadingApiLink to="/api/types/interface/ToolchainConfig#unstable_deno" />

Enables and configures [Deno](../guides/javascript/deno-handbook) using the new WASM plugin.

:::info

This toolchain requires the [`unstable_javascript`](#unstable_javascript) toolchain to also be
enabled.

:::

### `version`

<HeadingApiLink to="/api/types/interface/DenoConfig#version" />

Defines the explicit Deno toolchain
[version specification](../concepts/toolchain#version-specification) to use. If this field is _not
defined_, the global `deno` binary will be used.

```yaml title=".moon/toolchain.yml" {2}
unstable_deno:
  version: '2.0.0'
```

> Version can also be defined with [`.prototools`](../proto/config).

### `bins`

<HeadingApiLink to="/api/types/interface/DenoConfig#bins" />

A list of binaries to install globally into Deno (`~/.deno/bin`). This setting requires a list of
URLs or binary configuration objects with the following fields:

- `bin` (required) - URL of the binary.
- `name` - Provide a custom name for the binary.
- `local` - Only install the binary locally, and not in CI.
- `force` - Force install the binary. This _should_ be toggled for one-offs.

```yaml title=".moon/toolchain.yml" {2-5}
unstable_deno:
  bins:
    - 'https://deno.land/std@0.192.0/http/file_server.ts'
    - bin: 'https://deno.land/std@0.192.0/http/file_server.ts'
      name: 'fs'
```

### `executeArgs`

<HeadingApiLink to="/api/types/interface/DenoConfig#executeArgs" />

Customize the arguments that will be appended to all `deno`-based task commands. Arguments will be
appended after the `deno` executable, but before task specific arguments.

```yaml title=".moon/toolchain.yml" {2}
unstable_deno:
  executeArgs: ['--allow-read']
```

### `installArgs`

<HeadingApiLink to="/api/types/interface/DenoConfig#installArgs" />

Customize the arguments that will be passed to the `deno install` command, when the
`InstallDependencies` action is triggered in the pipeline. These arguments are used both locally and
in CI.

```yaml title=".moon/toolchain.yml" {2}
unstable_deno:
  installArgs: ['--frozen']
```

## `node`

<HeadingApiLink to="/api/types/interface/ToolchainConfig#node" />

Enables and configures [Node.js](../guides/javascript/node-handbook) using the legacy
implementation.

:::warning

This toolchain has been deprecated. We suggest using [`unstable_node`](#unstable_node) and a chosen
package manager ([`unstable_npm`](#unstable_npm), [`unstable_pnpm`](#unstable_pnpm), or
[`unstable_yarn`](#unstable_yarn)) instead!

:::

### `version`

<HeadingApiLink to="/api/types/interface/NodeConfig#version" />

Defines the explicit Node.js [version specification](../concepts/toolchain#version-specification) to
use. If this field is _not defined_, the global `node` binary will be used.

```yaml title=".moon/toolchain.yml" {2}
node:
  version: '16.13'
```

> Version can also be defined with [`.prototools`](../proto/config) or with the `MOON_NODE_VERSION`
> environment variable.

### `packageManager`

<HeadingApiLink to="/api/types/interface/NodeConfig#packageManager" />

Defines which package manager to utilize. Supports `npm` (default), `pnpm`, `yarn`, or `bun`.

```yaml title=".moon/toolchain.yml" {2}
node:
  packageManager: 'yarn'
```

### `npm`, `pnpm`, `yarn`, `bun`

<HeadingApiLink to="/api/types/interface/NodePackageManagerConfig" />

Optional fields for defining package manager specific configuration. The chosen setting is dependent
on the value of [`node.packageManager`](#packagemanager). If these settings _are not defined_, the
latest version of the active package manager will be used (when applicable).

#### `version`

<HeadingApiLink to="/api/types/interface/NpmConfig#version" />

The `version` setting defines the explicit package manager
[version specification](../concepts/toolchain#version-specification) to use. If this field is _not
defined_, the global `npm`, `pnpm`, `yarn`, and `bun` binaries will be used.

```yaml title=".moon/toolchain.yml" {4}
node:
  packageManager: 'yarn'
  yarn:
    version: '3.1.0'
```

> Version can also be defined with [`.prototools`](../proto/config) or with the `MOON_NPM_VERSION`,
> `MOON_PNPM_VERSION`, `MOON_YARN_VERSION`, or `MOON_BUN_VERSION` environment variables.

#### `installArgs`<VersionLabel version="1.22.0" />

<HeadingApiLink to="/api/types/interface/NpmConfig#installArgs" />

Customize the arguments that will be passed to the package manager's install command, when the
`InstallDeps` action is triggered in the pipeline. These arguments are used both locally and in CI.

```yaml title=".moon/toolchain.yml" {4}
node:
  packageManager: 'yarn'
  yarn:
    installArgs: ['--immutable']
```

### `yarn`

<HeadingApiLink to="/api/types/interface/NodeConfig#yarn" />

#### `plugins`

<HeadingApiLink to="/api/types/interface/YarnConfig#plugins" />

A list of plugins that will automatically be imported using `yarn plugin import` (Yarn 2+ only). For
performance reasons, plugins will only be imported when the Yarn version changes.

```yaml title=".moon/toolchain.yml" {4}
node:
  packageManager: 'yarn'
  yarn:
    version: '3.1.0'
    plugins:
      - 'interactive-tools'
      - 'workspace-tools'
```

### `addEnginesConstraint`

<HeadingApiLink to="/api/types/interface/NodeConfig#addEnginesConstraint" />

Injects the currently configured [Node.js version](#version) as an `engines` constraint to the root
`package.json` field. Defaults to `true`.

```yaml
node:
  addEnginesConstraint: true
```

For example, say our Node.js version is "16.15.0", and when we execute a run process through the
`moon` binary, it will update the root `package.json` with the below. We pin a fixed version to
ensure other Node.js processes outside of our toolchain are utilizing the same version.

```json title="package.json"
{
  // ...
  "engines": {
    "node": "16.15.0"
  }
}
```

### `binExecArgs`

<HeadingApiLink to="/api/types/interface/NodeConfig#binExecArgs" />

Additional [command line arguments](https://nodejs.org/api/cli.html) to pass to the `node` binary
when it's being executed by running a target. This will apply arguments to _all Node.js based_
targets, and cannot be changed on a per target basis.

```yaml title=".moon/toolchain.yml" {2-5}
node:
  binExecArgs:
    - '--preserve-symlinks'
    - '--loader'
    - '@boost/module/loader'
```

### `dedupeOnLockfileChange`

<HeadingApiLink to="/api/types/interface/NodeConfig#dedupeOnLockfileChange" />

Will dedupe dependencies after they have been installed, added, removing, or changed in any way, in
an effort to keep the workspace tree as clean and lean as possible. Defaults to `true`.

```yaml title=".moon/toolchain.yml" {2}
node:
  dedupeOnLockfileChange: true
```

### `dependencyVersionFormat`

<HeadingApiLink to="/api/types/interface/NodeConfig#dependencyVersionFormat" />

When [syncing project dependencies](#syncprojectworkspacedependencies), customize the format that
will be used for the dependency version range. The following formats are supported (but use the one
most applicable to your chosen package manager):

- `file` (npm default) - Uses `file:../relative/path` and copies package contents.
- `link` - Uses `link:../relative/path` and symlinks package contents.
- `star` - Uses an explicit `*`.
- `version` - Uses the explicit version from the dependent project's `package.json`, e.g., "1.2.3".
- `version-caret` - Uses the version from the dependent project's `package.json` as a caret range,
  e.g., "^1.2.3".
- `version-tilde` - Uses the version from the dependent project's `package.json` as a tilde range,
  e.g., "~1.2.3".
- `workspace` (bun/pnpm/yarn default) - Uses `workspace:*`, which resolves to "1.2.3". Requires
  package workspaces.
- `workspace-caret` - Uses `workspace:^`, which resolves to "^1.2.3". Requires package workspaces.
- `workspace-tilde` - Uses `workspace:~`, which resolves to "~1.2.3". Requires package workspaces.

```yaml title=".moon/toolchain.yml" {2}
node:
  dependencyVersionFormat: 'link'
```

> This setting does not apply to peer dependencies, as they will always use a format of
> `^<major>.0.0`. Furthermore, if a package manager does not support a chosen format, it will
> fallback to another format!

### `inferTasksFromScripts`

<HeadingApiLink to="/api/types/interface/NodeConfig#inferTasksFromScripts" />

Will infer and automatically create [tasks](../concepts/task) from `package.json` scripts. Defaults
to `false`.

This requires the [project's language](./project#language) to be "javascript" or "typescript", a
`package.json` to exist in the project, and will take the following into account:

- Script names will be converted to kebab-case, and will become the task ID.
- Pre, post, and life cycle hooks are ignored.
- Tasks defined in `.moon/tasks.yml` or `moon.yml` take precedence over scripts of the same name.

To verify inferred tasks, run [`moon project <id>`](../commands/project) (pass `--json` to view raw
config and options). Tasks that are inferred will run through the configured package manager.

```yaml title=".moon/toolchain.yml" {2}
node:
  inferTasksFromScripts: true
```

:::caution

This implementation shares functionality with
[`moon migrate from-package-json`](../commands/migrate/from-package-json), and will attempt to
determine environment variables, outputs, CI options, and more! Be aware of these when utilizing
this feature, especially in regards to `runInCI`, as it may be inaccurate!

:::

### `rootPackageOnly`

<HeadingApiLink to="/api/types/interface/NodeConfig#rootPackageOnly" />

Supports the "single version policy" or "one version rule" patterns by only allowing dependencies in
the root `package.json`, and only installing dependencies in the workspace root, and not within
individual projects. It also bypasses all `workspaces` checks to determine package locations.
Defaults to `false`.

```yaml title=".moon/toolchain.yml" {2}
node:
  rootPackageOnly: true
```

:::info

This setting _does not_ verify that other `package.json`s _do not_ have dependencies, it merely runs
"install dependency" commands in the root. It's up to you to ensure that other `package.json`s do
not have dependencies.

:::

### `syncPackageManagerField`<VersionLabel version="1.27.0" />

<HeadingApiLink to="/api/types/interface/NodeConfig#syncPackageManagerField" />

Will sync the currently configured [package manager](#packagemanager) and its version to the
`packageManager` field in the root `package.json`. This setting does nothing if the package manager
or version is not defined. Defaults to `true`.

```yaml title=".moon/toolchain.yml" {2}
node:
  syncPackageManagerField: true
  packageManager: pnpm
  pnpm:
    version: '9.0.0'
```

A quick example on how this works. Given the above, the following field will be injected:

```json title="package.json"
{
  // ...
  "packageManager": "pnpm@9.0.0"
}
```

### `syncProjectWorkspaceDependencies`

<HeadingApiLink to="/api/types/interface/NodeConfig#syncProjectWorkspaceDependencies" />

Will sync a project's [dependencies](../concepts/project#dependencies) as normal dependencies within
the project's `package.json`. If a dependent project does not have a `package.json`, or if a
dependency of the same name has an explicit version already defined, the sync will be skipped.
Defaults to `true`.

```yaml title=".moon/toolchain.yml" {2}
node:
  syncProjectWorkspaceDependencies: true
```

A quick example on how this works. Given the following `dependsOn`:

```yaml title="moon.yml"
dependsOn:
  - 'designSystem'
  - 'reactHooks'
```

Would result in the following `dependencies` within a project's `package.json`. The version format
can be customized with [`node.dependencyVersionFormat`](#dependencyversionformat).

```json title="package.json"
{
  // ...
  "dependencies": {
    "@company/design-system": "workspace:*",
    "@company/react-hooks": "workspace:*"
    // ...
  }
}
```

### `syncVersionManagerConfig`

<HeadingApiLink to="/api/types/interface/NodeConfig#syncVersionManagerConfig" />

Will sync the currently configured [Node.js version](#version) to a 3rd-party version manager's
config/rc file. Supports "nodenv" (syncs to `.node-version`), "nvm" (syncs to `.nvmrc`), or none
(default).

```yaml title=".moon/toolchain.yml" {2}
node:
  syncVersionManagerConfig: 'nvm'
```

This is a special setting that ensure other Node.js processes outside of our toolchain are utilizing
the same version, which is a very common practice when managing dependencies.

## `unstable_node`<VersionLabel version="1.40.0" />

<HeadingApiLink to="/api/types/interface/ToolchainConfig#unstable_node" />

Enables and configures [Node.js](../guides/javascript/node-handbook) using the new WASM plugin.

:::info

This toolchain requires the [`unstable_javascript`](#unstable_javascript) toolchain to also be
enabled.

:::

### `version`

<HeadingApiLink to="/api/types/interface/NodeConfig#version" />

Defines the explicit Node.js toolchain
[version specification](../concepts/toolchain#version-specification) to use. If this field is _not
defined_, the global `node` binary will be used.

```yaml title=".moon/toolchain.yml" {2}
unstable_node:
  version: '20.0.0'
```

> Version can also be defined with [`.prototools`](../proto/config).

### `executeArgs`

<HeadingApiLink to="/api/types/interface/NodeConfig#executeArgs" />

Customize the arguments that will be appended to all `node`-based task commands. Arguments will be
appended after the `node` executable, but before task specific arguments.

```yaml title=".moon/toolchain.yml" {2}
unstable_node:
  executeArgs: ['--preserve-symlinks']
```

### `profileExecution`

<HeadingApiLink to="/api/types/interface/NodeConfig#profileExecution" />

Enable the v8 profiler for all `node` executions, when configured as a task `command`. This should
only be temporarily enabled for debugging purposes, and not always enabled! Supports the following
options:

- `cpu` - Generate a CPU profile.
- `heap` - Generate a memory heap profile.

Profile snapshots will be written to a `.moon` directory in the current project.

```yaml title=".moon/toolchain.yml" {2}
unstable_node:
  profileExecution: 'cpu'
```

### `syncVersionManagerConfig`

<HeadingApiLink to="/api/types/interface/NodeConfig#syncVersionManagerConfig" />

Will sync the currently configured [Node.js version](#version) to a 3rd-party version manager's
config/rc file. Supports "nodenv" (syncs to `.node-version`), "nvm" (syncs to `.nvmrc`), or none
(default).

```yaml title=".moon/toolchain.yml" {2}
unstable_node:
  syncVersionManagerConfig: 'nvm'
```

This is a special setting that ensure other Node.js processes outside of our toolchain are utilizing
the same version, which is a very common practice when managing dependencies.

## `unstable_npm`<VersionLabel version="1.40.0" />

<HeadingApiLink to="/api/types/interface/ToolchainConfig#unstable_npm" />

Enables and configures npm using the new WASM plugin.

:::info

This toolchain requires the [`unstable_node`](#unstable_node) toolchain to also be enabled.

:::

### `version`

<HeadingApiLink to="/api/types/interface/NpmConfig#version" />

Defines the explicit npm toolchain
[version specification](../concepts/toolchain#version-specification) to use. If this field is _not
defined_, the global `npm` binary will be used.

```yaml title=".moon/toolchain.yml" {2}
unstable_npm:
  version: '9.0.0'
```

> Version can also be defined with [`.prototools`](../proto/config).

### `installArgs`

<HeadingApiLink to="/api/types/interface/NpmConfig#installArgs" />

Customize the arguments that will be passed to the `npm install` command, when the
`InstallDependencies` action is triggered in the pipeline. These arguments are used both locally and
in CI.

```yaml title=".moon/toolchain.yml" {2}
unstable_npm:
  installArgs: ['--no-save']
```

> This setting is referenced by the `unstable_javascript` toolchain.

## `unstable_pnpm`<VersionLabel version="1.40.0" />

<HeadingApiLink to="/api/types/interface/ToolchainConfig#unstable_pnpm" />

Enables and configures pnpm using the new WASM plugin.

:::info

This toolchain requires the [`unstable_node`](#unstable_node) toolchain to also be enabled.

:::

### `version`

<HeadingApiLink to="/api/types/interface/PnpmConfig#version" />

Defines the explicit pnpm toolchain
[version specification](../concepts/toolchain#version-specification) to use. If this field is _not
defined_, the global `pnpm` binary will be used.

```yaml title=".moon/toolchain.yml" {2}
unstable_pnpm:
  version: '9.0.0'
```

> Version can also be defined with [`.prototools`](../proto/config).

### `installArgs`

<HeadingApiLink to="/api/types/interface/PnpmConfig#installArgs" />

Customize the arguments that will be passed to the `pnpm install` command, when the
`InstallDependencies` action is triggered in the pipeline. These arguments are used both locally and
in CI.

```yaml title=".moon/toolchain.yml" {2}
unstable_pnpm:
  installArgs: ['--frozen-lockfile']
```

> This setting is referenced by the `unstable_javascript` toolchain.

## `unstable_yarn`<VersionLabel version="1.40.0" />

<HeadingApiLink to="/api/types/interface/ToolchainConfig#unstable_yarn" />

Enables and configures yarn using the new WASM plugin.

:::info

This toolchain requires the [`unstable_node`](#unstable_node) toolchain to also be enabled.

:::

### `version`

<HeadingApiLink to="/api/types/interface/YarnConfig#version" />

Defines the explicit yarn toolchain
[version specification](../concepts/toolchain#version-specification) to use. If this field is _not
defined_, the global `yarn` binary will be used.

```yaml title=".moon/toolchain.yml" {2}
unstable_yarn:
  version: '4.0.0'
```

> Version can also be defined with [`.prototools`](../proto/config).

### `installArgs`

<HeadingApiLink to="/api/types/interface/YarnConfig#installArgs" />

Customize the arguments that will be passed to the `yarn install` command, when the
`InstallDependencies` action is triggered in the pipeline. These arguments are used both locally and
in CI.

```yaml title=".moon/toolchain.yml" {2}
unstable_yarn:
  installArgs: ['--immutable']
```

> This setting is referenced by the `unstable_javascript` toolchain.

### `plugins`

<HeadingApiLink to="/api/types/interface/YarnConfig#plugins" />

A list of plugins that will automatically be imported using `yarn plugin import` (Yarn 2+ only). For
performance reasons, plugins will only be imported when the Yarn version changes.

```yaml title=".moon/toolchain.yml" {2-4}
unstable_yarn:
  plugins:
    - 'interactive-tools'
    - 'workspace-tools'
```

## `typescript`

<HeadingApiLink to="/api/types/interface/ToolchainConfig#typescript" />

Dictates how moon interacts with and utilizes TypeScript within the workspace. This field is
optional and is undefined by default. Define it to enable TypeScript support.

### `createMissingConfig`

<HeadingApiLink to="/api/types/interface/TypeScriptConfig#createMissingConfig" />

When [syncing project references](#syncprojectreferences) and a depended on project _does not_ have
a `tsconfig.json`, automatically create one. Defaults to `true`.

```yaml title=".moon/toolchain.yml" {2}
typescript:
  createMissingConfig: true
```

### `includeProjectReferenceSources`<VersionLabel version="1.17.0" />

<HeadingApiLink to="/api/types/interface/TypeScriptConfig#includeProjectReferenceSources" />

When enabled and [syncing project references](#syncprojectreferences), will inject each project
reference as an entry in the `include` field of the respective project's `tsconfig.json`. These
includes are sometimes required by editors for auto-completion, intellisense, and automatic imports.

```yaml title=".moon/toolchain.yml" {2}
typescript:
  includeProjectReferenceSources: true
```

To demonstrate this, we'll use the example from [`syncProjectReferences`](#syncprojectreferences).
When this setting is enabled, the `include` field will also be populated.

```json title="tsconfig.json"
{
  // ...
  "include": ["../../design-system/**/*", "../../react-hooks/**/*"],
  "references": [
    // ...
    { "path": "../../design-system" },
    { "path": "../../react-hooks" }
  ]
}
```

### `includeSharedTypes`<VersionLabel version="1.17.0" />

<HeadingApiLink to="/api/types/interface/TypeScriptConfig#includeSharedTypes" />

When enabled, will automatically inject shared types (`types/**/*`) into the `include` field of each
project's `tsconfig.json`. The shared types folder _must_ be named `types` and must exist relative
to the [`root`](#root) setting. Defaults to `false`.

```yaml title=".moon/toolchain.yml" {2}
typescript:
  includeSharedTypes: true
```

As a demonstration, if we had a package located at "packages/components", the `include` setting will
be appended with:

```json title="<project>/tsconfig.json"
{
  // ...
  "include": ["../../types/**/*"]
}
```

### `projectConfigFileName`

<HeadingApiLink to="/api/types/interface/TypeScriptConfig#projectConfigFileName" />

Defines the file name of the `tsconfig.json` found in the project root. We utilize this setting when
syncing project references between projects. Defaults to `tsconfig.json`.

```yaml title=".moon/toolchain.yml" {2}
typescript:
  projectConfigFileName: 'tsconfig.build.json'
```

### `root`

<HeadingApiLink to="/api/types/interface/TypeScriptConfig#root" />

Defines the TypeScript root (relative from moon's workspace root), where project reference
composition, common compiler options, and shared types will be located. Defaults to `.`.

```yaml title=".moon/toolchain.yml" {2}
typescript:
  root: './types'
```

### `rootConfigFileName`

<HeadingApiLink to="/api/types/interface/TypeScriptConfig#rootConfigFileName" />

Defines the file name of the `tsconfig.json` found in the root of all projects. We utilize this
setting when syncing projects as references. Defaults to `tsconfig.json`.

```yaml title=".moon/toolchain.yml" {2}
typescript:
  rootConfigFileName: 'tsconfig.projects.json'
```

### `rootOptionsConfigFileName`

<HeadingApiLink to="/api/types/interface/TypeScriptConfig#rootOptionsConfigFileName" />

Defines the file name of the config file found in the root that houses shared compiler options.
Defaults to `tsconfig.options.json`. This setting is used in the following scenarios:

- When [creating a `tsconfig.json` for a project](#), sets the `extends` field to this value.

```yaml title=".moon/toolchain.yml" {2}
typescript:
  rootOptionsConfigFileName: 'tsconfig.base.json'
```

### `routeOutDirToCache`

<HeadingApiLink to="/api/types/interface/TypeScriptConfig#routeOutDirToCache" />

Updates the `outDir` compiler option in each project's [`tsconfig.json`](#projectconfigfilename) to
route to moon's cache folder. This is useful when using project references and wanting to keep all
the compiled `.d.ts` files _out_ of the project folder. Defaults to `false`.

```yaml title=".moon/toolchain.yml" {2}
typescript:
  routeOutDirToCache: true
```

As a demonstration, if we had a package located at "packages/components", the `outDir` compiler
option will be re-routed to the following when syncing.

```json title="<project>/tsconfig.json"
{
  // ...
  "compilerOptions": {
    // ...
    "outDir": "../../.moon/cache/types/packages/components"
  }
}
```

### `syncProjectReferences`

<HeadingApiLink to="/api/types/interface/TypeScriptConfig#syncProjectReferences" />

Will sync a project's [dependencies](../concepts/project#dependencies) (when applicable) as project
references within that project's `tsconfig.json`, and the root `tsconfig.json`. Defaults to `true`
when the parent `typescript` setting is defined, otherwise `false`.

```yaml title=".moon/toolchain.yml" {2}
typescript:
  syncProjectReferences: true
```

A quick example on how this works. Given the following dependencies:

```yaml title="moon.yml"
dependsOn:
  - 'designSystem'
  - 'reactHooks'
```

Would result in the following `references` within both `tsconfig.json`s.

```json title="tsconfig.json"
{
  // ...
  "references": [
    // ...
    { "path": "../../design-system" },
    { "path": "../../react-hooks" }
  ]
}
```

:::info

This setting assumes you're using the file organization as defined in our official
[TypeScript project references](../guides/javascript/typescript-project-refs) in-depth guide.

:::

### `syncProjectReferencesToPaths`

<HeadingApiLink to="/api/types/interface/TypeScriptConfig#syncProjectReferencesToPaths" />

Will sync a project's [`tsconfig.json`](#projectconfigfilename) project references to the `paths`
compiler option, using the referenced project's `package.json` name. This is useful for mapping
aliases to their source code. Defaults to `false`.

```yaml title=".moon/toolchain.yml" {2}
typescript:
  syncProjectReferencesToPaths: true
```

As a demonstration, if we had a reference to a shared package with the name `@brand/components`, the
`paths` compiler option would be updated to the following when syncing.

If an index file exists, we'll map a default import. Otherwise, we'll always map a wildcard import.
Both imports can optionally be nested within a `src` directory.

```json title="<project>/tsconfig.json"
{
  // ...
  "compilerOptions": {
    // ...
    "paths": {
      "@brand/components": ["../shared/components/src/index.ts"],
      "@brand/components/*": ["../shared/components/src/*"]
    }
  },
  "references": [
    {
      "path": "../shared/components"
    }
  ]
}
```

> This setting runs _after_ [`syncProjectReferences`](#syncprojectreferences) and will inherit any
> synced references from that setting.

## Python<VersionLabel version="1.30.0" />

## `python`

<HeadingApiLink to="/api/types/interface/ToolchainConfig#python" />

Enables and configures [Python](https://www.python.org/).

### `version`

<HeadingApiLink to="/api/types/interface/PythonConfig#version" />

Defines the explicit Python toolchain
[version specification](../concepts/toolchain#version-specification) to use. If this field is _not
defined_, the global `python` binary will be used.

```yaml title=".moon/toolchain.yml" {2}
python:
  version: '3.11.10'
```

:::info

Python installation's are based on pre-built binaries provided by
[astral-sh/python-build-standalone](https://github.com/astral-sh/python-build-standalone).

:::

> Version can also be defined with [`.prototools`](../proto/config).

### `packageManager`<VersionLabel version="1.32.0" />

<HeadingApiLink to="/api/types/interface/PythonConfig#packageManager" />

Defines which package manager to utilize. Supports `pip` (default) or `uv`.

```yaml title=".moon/toolchain.yml" {2}
python:
  packageManager: 'uv'
```

### `rootVenvOnly`<VersionLabel version="1.32.0" />

<HeadingApiLink to="/api/types/interface/PythonConfig#rootvenvonly" />

Supports the "single version policy" or "one version rule" patterns by only allowing dependencies in
the root `requirements.txt` (pip) or `uv.lock` (uv), and only installing dependencies in the
workspace root, and not within individual projects. It also bypasses all `workspaces` checks to
determine package locations.

```yaml title=".moon/toolchain.yml" {2}
python:
  rootVenvOnly: true
```

### `venvName`

<HeadingApiLink to="/api/types/interface/PythonConfig#venvName" />

Defines the virtual environment name, which will be created in the workspace or project root when a
`requirements.txt` exists, and where dependencies will be installed into. Defaults to `.venv`

```yaml title=".moon/toolchain.yml" {2}
python:
  venvName: '.my-custom-venv'
```

### `pip`

<HeadingApiLink to="/api/types/interface/PythonConfig#pip" />

Optional fields for defining pip specific configuration.

#### `installArgs`

<HeadingApiLink to="/api/types/interface/PipConfig#installargs" />

Customize the arguments that will be passed to the pip install command, when the `InstallDeps`
action is triggered in the pipeline. These arguments are used both locally and in CI.

```yaml title=".moon/toolchain.yml" {3}
python:
  pip:
    installArgs: ['--trusted-host company.repo.com', '-i https://company.repo.com/simple']
```

### `uv`<VersionLabel version="1.32.0" />

<HeadingApiLink to="/api/types/interface/PythonConfig#uv" />

Optional fields for defining uv specific configuration.

#### `syncArgs`

<HeadingApiLink to="/api/types/interface/UvConfig#syncargs" />

Customize the arguments that will be passed to the uv sync command, when the `InstallDeps` action is
triggered in the pipeline. These arguments are used both locally and in CI.

```yaml title=".moon/toolchain.yml" {4}
python:
  packageManager: 'uv'
  uv:
    syncArgs: ['--all-packages']
```

#### `version`

<HeadingApiLink to="/api/types/interface/UvConfig#version" />

Defines the explicit uv toolchain
[version specification](../concepts/toolchain#version-specification) to use. If this field is _not
defined_, the global `uv` binary will be used.

```yaml title=".moon/toolchain.yml" {4}
python:
  packageManager: 'uv'
  uv:
    version: '0.5.26'
```

## Rust

## `rust`<VersionLabel version="1.5.0" />

<HeadingApiLink to="/api/types/interface/ToolchainConfig#rust" />

Enables and configures [Rust](../guides/rust/handbook) using the legacy implementation.

:::warning

This toolchain has been deprecated. We suggest using [`unstable_rust`](#unstable_rust) instead!

:::

### `version`

<HeadingApiLink to="/api/types/interface/RustConfig#version" />

Defines the explicit Rust toolchain
[version/channel specification](../concepts/toolchain#version-specification) to use. If this field
is _not defined_, the global `cargo`, `rustc`, and other binaries will be used.

```yaml title=".moon/toolchain.yml" {2}
rust:
  version: '1.69.0'
```

> Version can also be defined with [`.prototools`](../proto/config).

### `bins`<VersionLabel version="1.10.0" updated />

<HeadingApiLink to="/api/types/interface/RustConfig#bins" />

A list of binaries (with optional versions) to install into Cargo (`~/.cargo/bin`), and make them
available to the `cargo` command. Binaries will be installed with
[`cargo-binstall`](https://crates.io/crates/cargo-binstall) in an effort to reduce build and
compilation times.

This setting requires a list of package names or binary configuration objects with the following
fields:

- `bin` (required) - Name of the binary.
- `local` - Only install the binary locally, and not in CI.
- `force` - Force install the binary. This _should_ be toggled for one-offs.

```yaml title=".moon/toolchain.yml" {2-5}
rust:
  bins:
    - 'cargo-nextest@0.9.52'
    - bin: 'cargo-nextest'
      local: true
```

Binaries that have been installed into Cargo can be referenced from task commands:

```yaml title="<project>/moon.yml"
tasks:
  test:
    command: 'nextest run --workspace'
```

### `binstallVersion`<VersionLabel version="1.30.0" />

<HeadingApiLink to="/api/types/interface/RustConfig#binstallVersion" />

The version of [`cargo-binstall`](https://crates.io/crates/cargo-binstall) to install if it does not
already exist. Defaults to "latest" if not configured.

```yaml title=".moon/toolchain.yml" {2}
rust:
  binstallVersion: '1.10.12'
```

### `components`<VersionLabel version="1.16.0" />

<HeadingApiLink to="/api/types/interface/RustConfig#components" />

A list of additional [components](https://rust-lang.github.io/rustup/concepts/components.html) to
automatically install with `rustup` for the current toolchain. Will be installed when the pipeline
is first ran, and subsequently when configuration changes.

```yaml title=".moon/toolchain.yml" {2-4}
rust:
  components:
    - 'rust-docs'
    - 'rust-analyzer'
```

### `syncToolchainConfig`

<HeadingApiLink to="/api/types/interface/RustConfig#syncToolchainConfig" />

Will automatically sync the currently configured [Rust `version`](#version-2) to the
`toolchain.channel` field in `rust-toolchain.toml`, relative to the root `Cargo.lock`. If the file
does not exist, it will be created.

This is a special setting that ensures other Rust/Cargo processes outside of our toolchain are
utilizing the same version, which is a very common practice.

```yaml title=".moon/toolchain.yml" {2,3}
rust:
  version: '1.69.0'
  syncToolchainConfig: true
```

To demonstrate this, the settings above would sync the following file:

```toml title="rust-toolchain.toml"
[toolchain]
channel = "1.69.0"
```

### `targets`<VersionLabel version="1.16.0" />

<HeadingApiLink to="/api/types/interface/RustConfig#targets" />

A list of additional [targets](https://rust-lang.github.io/rustup/cross-compilation.html) to
automatically install with `rustup` for the current toolchain. Will be installed when the pipeline
is first ran, and subsequently when configuration changes.

```yaml title=".moon/toolchain.yml" {2-4}
rust:
  targets:
    - 'aarch64-unknown-linux-gnu'
    - 'wasm32-wasi'
```

> Targets are currently _not scoped_ based on operating system, and will be installed for all
> machines.

## `unstable_rust`<VersionLabel version="1.37.0" />

<HeadingApiLink to="/api/types/interface/ToolchainConfig#rust" />

Enables and configures [Rust](../guides/rust/handbook). This setting enables the new WASM powered
Rust toolchain, which is far more accurate and efficient, but still unstable.

Supports all the same settings as [`rust`](#rust), with the addition of:

### `addMsrvConstraint`<VersionLabel version="1.37.0" />

<HeadingApiLink to="/api/types/interface/RustConfig#addMsrvConstraint" />

When `version` is defined, syncs the version as a constraint to `Cargo.toml` under the
`workspace.package.rust-version` or `package.rust-version` fields.

```yaml title=".moon/toolchain.yml" {2}
unstable_rust:
  addMsrvConstraint: true
```
